home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / tools / czesc_2 / lettermatcher / lettermatcher.doc < prev    next >
Text File  |  1993-08-11  |  10KB  |  251 lines
  1.  
  2.                             Tired of these old
  3.  
  4.     LLLL          OOOOOOOOOO    GGGGGGGGGG    OOOOOOOOOO    SSSSSSSSSS
  5.     LLLL         OOOO    OOOO  GGGG    GGGG  OOOO    OOOO  SSSS    SSSS
  6.     LLLL         OOOO    OOOO  GGGG    GGGG  OOOO    OOOO  SSSS
  7.     LLLL         OOOO    OOOO  GGGG          OOOO    OOOO   SSSSSSSSSS
  8.     LLLL         OOOO    OOOO  GGGG  GGGGGG  OOOO    OOOO          SSSS
  9.     LLLL         OOOO    OOOO  GGGG    GGGG  OOOO    OOOO  SSSS    SSSS
  10.     LLLL         OOOO    OOOO  GGGG    GGGG  OOOO    OOOO  SSSS    SSSS
  11.      LLLLLLLLLL   OOOOOOOOOO    GGGGGGGGGG    OOOOOOOOOO    SSSSSSSSSS
  12.  
  13.                                    ????
  14.  
  15.                               If so, then ...
  16.                  _wæ*°"9æ,
  17.                 gØ°     â#
  18.               _dH´     _#@
  19.             Xg#Ø      gØP            æ´   ø
  20.              #Øùw_wwæØ@"            dF   dP
  21.             dØ   ¯¯¯               J@   J#
  22.            ¸Ø´           ¸w-mw_  -g#^^-g#9^ ,a*ww_ _æw,¸wwp
  23.            Æ´          _¥"   §#  ,#F  ,#F ,/    #b ¬g#b°"¬²
  24.           Æ"           Ø  __wÆ"  ØF   ØF ,P  _wæP" _#P
  25.   _wæwwww@            ÍL ^"¯    ØK   ØK  ØL·°"     ÆF
  26.  ¡#_ __ض#µww____òm   ]#,  _w  d#_  d@_  ¶#_  _w  JP
  27.  ¬@*#P"   "9**@P°      °M*Æ"   #°   @°    °M#P¯   *
  28.         ___wwww___         __ww¸
  29.       _æ@°"¯¯¬"°°@*mww_  _*" J@"
  30.  ___ a"   w      ,   ¬°¶@*-^°¯                        _wd'
  31. dP¯¯7´ _wØ~     æ´    g°                  w           ¯#P
  32. °^+æb*¤"W"    _dK   _w"                  dP           d@
  33.     9_ dF  _,mS@   _Ø                   J#           dØ
  34.      ¬WØÝ*¤" ,#   g#           __wwa  -g#** _ww_    J#´ _a_   _www_   _w¸ ùw_
  35.      g#´    ,#´   #¹         wæP" æc  ,#F g°¯ ¬#    #Ew¤"#F _æ"  `#z ¤9#þ*°¶F
  36.     ,#F    ,#þ   d#        gØ°   dP   ØP d"   °9   ØP"  d@ ,@   _æM° _Ø@"
  37.    ,#@    ¸#Ø    ##       dØ   _dØ   ØP z#        dØ   JH  #F *°"    ÆP
  38.   ,##     Ø#F    ##       #  _w##¹  dØ  |#    g  JH´  ,#´_ #L    _  ,@
  39.  J##F    Ø##     ##w_w°  ¬#Ñ*°¯#@~ jH*"  ¶#ææ°¯ aHF   #@°¯ ¬MWææ°¯ ,#    V1.0
  40.                   ""¯
  41.                              is just for you.
  42.  
  43. So what the heck is LetterMatcher ?
  44. -----------------------------------
  45.  
  46. LetterMatcher lets you create character representations of bitmap images.
  47. This way, you can design your logos in any paint program and have them
  48. converted to ascii text output.  There are some programs that do this by
  49. using Amigas own ansi-sequences and building the image row by row but
  50. LetterMatcher creates ordinary ascii output, and even 7-bit if you want it.
  51.  
  52. Some other novelty uses for LetterMatcher might be:
  53.  
  54. - Make those wacky ``if you take a step back you can just make out the
  55.   face of Queen Elizabeth II from this mess of characters'' pictures
  56. - Make large graphical banners with your text-only printer
  57. - Design IBM-character menus (for your BBS) in a paint program
  58.   (if you really want to abuse LetterMatcher)
  59.  
  60.  
  61. How to use LetterMatcher
  62. ------------------------
  63.  
  64. For a quick list of available options you can type 'LetterMatcher' in your
  65. CLI.  LetterMatcher is a CLI only utility, no other interface is currently
  66. provided.
  67.  
  68. Currently the source bitmap must be in raw format.  Use any available iff
  69. to raw converter to get raw bitmap data from your iff pictures.
  70.  
  71. The source image must also be one bitplane deep (2 colors) as must be the
  72. source raw bitmap you pass to LetterMatcher.
  73.  
  74. The command line syntax is:
  75.  
  76. LetterMatcher [-stmlq] OutName Picture Width Height [FontRange [FontName]]
  77.  
  78. Where:
  79.  
  80. Outname <filename, can be inserted in quotes like "File Name">
  81.  
  82. is the name of the output text file created from your Picture.
  83.  
  84. Picture <filename, can be inserted in quotes like "File Name">
  85.  
  86. is the source raw bitmap data file.
  87.  
  88. Width <integer value, must be divisible by 8>
  89.  
  90. is the width of your picture in pixels (max 2048).  The width of your
  91. picture MUST be divisible by 8, otherwise LetterMatcher will complain.  If
  92. you specify a wrong value for the width (other than the original width of
  93. your picture) you get screwy output (slantig horizontal lines).
  94.  
  95. Height <integer value, divisible by 8>
  96.  
  97. is the number of lines to convert from your Picture.  If you specify the
  98. full height of your source Picture or greater, the whole Picture is
  99. converted.  Note that this also should be divisible by 8.  Height is always
  100. rounded downwards to the nearest number divisible by 8.
  101.  
  102. FontRange <byte values, separated with commas ',' or minuses '-'>
  103.  
  104. specifies the characters to use for matching in your font.  The default
  105. FontRange is 32-126,160-254 which gives you all the printable characters in
  106. topaz.font.  The example FontRange 3-6,21,32-126,128-254 makes it possible
  107. for your output to contain the characters 3-6,21,32-126,128-254 and not the
  108. characters 0-2,7-20,22-31,127,255.
  109.  
  110. FontName <name of font with the .font suffix>
  111.  
  112. specifies the font to use for matching.  The font must be 8 pixels wide and
  113. 8 pixels high and it must be nonproportional.  This makes it possible to
  114. use your olde topaz and the many ibm-style fonts that come with comms
  115. packages.  Default is the topaz.font.
  116.  
  117. -s <a switch, if it is in the command line it is on>
  118.  
  119. Strip trailing spaces from your output.
  120.  
  121. -t <a switch, if it is in the command line it is on>
  122.  
  123. Display the time elapsed while matching your picture in EClock ticks.
  124.  
  125. -m <a switch, if it is in the command line it is on>
  126.  
  127. Add a CR/LF pair after each output line.  If this switch is not in the
  128. command line only LF is added.  CR/LF is usefull for printing purposes.
  129.  
  130. -l <a switch, if it is in the command line it is on>
  131.  
  132. Loose matching of characters.  This gives you a slightly different output
  133. and is about twice as fast as the normal matching.  Sometimes the output
  134. with this switch can even look better.
  135.  
  136. -q <a switch, if it is in the command line it is on>
  137.  
  138. Suppress any CLI output but error messages.  If this switch is in the
  139. command line no matching information is outputted to your CLI.  Note that
  140. timing information is still printed, if the switch -t is on.
  141.  
  142. OutName, Picture, Width and Height MUST be provided in the command line.
  143. The switches -stmlq are optional.  The switches and options MUST be in the
  144. order specified in the command line syntax above.  FontRange and FontName
  145. are also optional and if you want to specify a FontName you MUST also
  146. specify a FontRange.
  147.  
  148.  
  149. Theory of operation
  150. -------------------
  151.  
  152. Each 8x8 rectangle of the source bitmap is matched with all of the defined
  153. characters in the font.  The character that has the highest number of
  154. matching pixels is displayed in the resulting output.
  155.  
  156. Currently the program runs somewhat slowly, and I've tried to speed it up
  157. as much as I could.  The innermost loop is unrolled for maximum speed under
  158. 68000 making the loop 566 bytes in size.  Sorry for the 256 byte cache
  159. owners.  You can roll these loops tight again.
  160.  
  161. After all, the number of matches to make for a single picture is quite
  162. large (example picture 640x400):
  163.  
  164. source rectangle 8x8 pixels  = 64 pixels
  165. target rectangle 8x8 pixels  = 64 pixels
  166. number of font characters    = 256
  167. picture width in characters  = 640/8 = 80
  168. picture height in characters = 400/8 = 50
  169. total source rectangles      = 80x50 = 4000
  170. to match with 256 target rectangles of 64 pixels each
  171.  
  172. so in total 64*4000*256 = 65536000 pixel matchings
  173.  
  174. The work load is made smaller by matching totals of 32+32 pixels in each
  175. iteration thus making it down to 1024000 matches.
  176.  
  177. I'm sure there is a better and quicker way to do this with a smaller amount
  178. of pixels to match, but this is how I've done it.  Of course, some
  179. optimizations are made.  If a perfect match for an 8x8 area is found no
  180. more characters are matched.  This boosts up the matching speed of pictures
  181. that have a lot of empty spaces in them tremendously.
  182.  
  183. The more loose matching method works by or'ing the matching pixels of the
  184. upper 4x8 and lower 4x8 areas of the source and the target and then
  185. counting the matching pixels.  Giving a pretty good approximation of the
  186. number of matching pixels in each 8x8 rectangle.
  187.  
  188. Of course, using a smaller font range will speed up the matching.
  189.  
  190.  
  191. Fiddling with the result
  192. ------------------------
  193.  
  194. The obvious thing to try is to generate a different output with the -l
  195. switch on.
  196.  
  197. Another thing to try is to change the x- and y-offsets of your source
  198. bitmap.  Since the matching is done in 8x8 rectangles you have 64 possible
  199. starting offsets for your bitmap.  Each of these produces a different
  200. output.  A clarifying illustration of this follows:
  201.  
  202.   1 2 3 4 5 6 7 8
  203.  +-+-+-+-+-+-+-+-+
  204. 1: : : : : : : : : :
  205.  +-+-+-+-+-+-+-+-+ :
  206. 2: : : : : : : : : :
  207.  +-+-+-+-+-+-+-+-+ :
  208. 3: : : : : : : : : V
  209.  +-+-+-+-+-+-+-+-+  
  210. 4: : : : :X:X:X:X: y-offset
  211.  +-+-+-+-+-+-+-+-+
  212. 5: : : : :X: : : :
  213.  +-+-+-+-+-+-+-+-+
  214. 6: : : : :X: : : :
  215.  +-+-+-+-+-+-+-+-+
  216. 7: : : : :X: : : :
  217.  +-+-+-+-+-+-+-+-+
  218. 8: : : : :X: : : :
  219.  +-+-+-+-+-+-+-+-+
  220.  
  221.   ------> x-offset
  222.  
  223.  
  224. The Disclaimer
  225. --------------
  226.  
  227. If this program eats your dog or blows up your hard drive, I'm not in
  228. any way responsible.  (no, I'm not responsible for any other kind of
  229. damage you may acquire whilst using this program)
  230.  
  231.  
  232. The Author
  233. ----------
  234.  
  235. This particularly magnificent piece of coding was done by Henri Veisterä.
  236. Version 1.0 was finished some time in August 1993.  You can leave me e-mail
  237. at hveister@niksula.hut.fi if you have some comments or suggestions to
  238. make.  There are no bugs in this program =).
  239.  
  240.  
  241. Distribution
  242. ------------
  243.  
  244. LetterMatcher is PD.  Do whit it what ever you want.  If you want to
  245. distribute modified versions of LetterMatcher indicate somewhere in the
  246. distribution that it is a modified version.
  247.  
  248. For instance, loading of iff-pictures should be trivial to add if you
  249. already have the code ready, or use an external library.
  250.  
  251.